Agent-Recall

The problem

AI agents are stateless by design. They enter every new task with zero awareness of what they accomplished in the prior session. If an agent is asked to write a CSV parser, debug a port conflict, or integrate a specific API, it starts from first principles. It writes the code from scratch, rediscovers the same quirks, and wastes expensive LLM tokens rewriting boilerplate.

In production systems, this statelessness is highly inefficient. Developers don't work this way; they check their history, copy snippets of what worked, and adapt old templates. Agent-Recall gives agents a local memory bank of past successes. If the agent completes a task successfully, the solution is recorded. If a similar goal is submitted, the system fetches the old approach and forces the agent to read it before writing new code.

How it works: step by step

Step 1: Record successful solutions. When an agent completes a task, the orchestrator records the event to ./data/solutions.json. The record stores four critical fields: the prompt goal, the technical approach (what modules were used), the outcome (the success state), and a confidence score.
Step 2: Tokenize new goals. When a new task arrives, both the new goal and the stored goals are tokenized. The text is converted to lowercase, special characters are stripped, and common filler words (like "a", "the", "to", "and") are removed.
Step 3: Calculate keyword-overlap similarity. It calculates a Jaccard-like similarity score by dividing the number of overlapping tokens by the size of the larger token set. If the similarity exceeds a preconfigured threshold (default 0.3), the solution is flagged.
Step 4: Build the recall block. The matching database record is formatted into a clean markdown block. This block outlines the similarity percentage, the prior goal, the exact files and methods used, and advice on how to build on top of it.
Step 5: Prepend to prompt. The orchestrator prepends this recall block directly to the agent's prompt, serving as an instant reference.

Interactive: Jaccard Keyword Similarity Calculator

Compare two tasks to see how the system calculates similarity and formats the recall block. We use keyword overlap (v1) to run offline without embeddings.

Input Tasks

Result

33% Match

### RECALL: Similar Task Found in Memory
Similarity: 33%
Prior Goal: Write a CSV parser
How it was solved: Used fs.readFileSync, split by newlines.
Outcome: Working script
Confidence: 90%
Consider this approach before starting from scratch.
### END RECALL

How similarity calculations work

Agent-Recall uses keyword tokenization instead of semantic vector databases in its standard mode. This allows it to work entirely offline, with zero latency and zero dependency on external embedding providers.

Goal A: "Write a CSV parser" -> tokens: [write, csv, parser]
Goal B: "Parse a CSV file"   -> tokens: [parse, csv, file]

Intersection: {csv} = 1
Max set length: max(3, 3) = 3
Similarity: 1 / 3 = 0.33 (33%)

The recall block: what the agent reads

### RECALL: Similar Task Found in Memory
Similarity: 68%
Prior Goal: Write a function to parse CSV files in Node.js
How it was solved: Used fs.readFileSync, split by newlines, then by comma. Handled quoted fields with regex.
Outcome: Working CSV parser, 40 lines, handles edge cases
Confidence: 90%
Consider this approach before starting from scratch.
### END RECALL

How to run it

git clone https://github.com/shubham0086/Agent-Recall
cd Agent-Recall
npm install

# Run the memory demo script
node demo/recall.js

The API

import { Recall } from 'agent-recall';

// 1. Instantiate with workspace identifier
const memory = new Recall('my-workspace');

// 2. Store a successful task solution
await memory.storeSolution(
    "Parse CSV strings into arrays",
    "Used line split and regex commas",
    "Completed successfully, 12 test cases passed",
    95
);

// 3. Search recall context for new task
const context = await memory.buildRecallContext("Parse values from a raw CSV file");
if (context) {
    console.log("Prepending context block to prompt...");
}

Where this fits

Agent-Recall represents the cross-session memory layer of the autonomy ladder. It implements Pattern 03 (Reality-First Memory) in Agentic Patterns. In production engines, this works alongside Agent-Scars (which tracks failures) to form the dual-memory stack inside AgentKernel.

Honest framing

Since this Jaccard overlap relies on matching words, synonyms can cause misses. If Goal A is "Fetch web pages" and Goal B is "Retrieve HTML content", the Jaccard similarity is zero, even though they describe the same task. The v2 roadmap incorporates local, light-weight semantic embedding models (like transformers.js) to resolve this limitation. However, in standard developer workloads, using consistent vocabulary (like "GET", "fetch", "auth", "validate") yields matching rates above 80% with zero overhead.

Cross-Session Recall System : Annotated Reference